Docs: Update template code, documentation page for the DNF5 Command Template #1994
Conversation
The `.. literalinclude::`s for the code in `doc/templates/command/` were using `:lines:` arguments that excluded the first line, which is the `#ifndef` for the include guards. That's kind of important.
Bring code in `doc/templates/command/` up to date with latest internal API changes; code tested and working when compiled in to current HEAD codebase.
- Add a section heading for each file - Move filenames to listing captions - Make integration instructions into a section, and add a CAUTION admonishment that plugin authors should ignore it - Link from caution message to next template (DNF5 Plugin Template)
|
Plus it seems there is a couple formatting issues, see the |
| foo_option = dynamic_cast<libdnf5::OptionBool *>( | ||
| parser.add_init_value(std::unique_ptr<libdnf5::OptionBool>(new libdnf5::OptionBool(false)))); | ||
| parser.add_init_value( | ||
| std::unique_ptr<libdnf5::OptionBool>( | ||
| new libdnf5::OptionBool(false)))); |
There was a problem hiding this comment.
@kontura My only problem with this (which the pre-commit formatter wants to change back to the un-wrapped format:)
foo_option = dynamic_cast<libdnf5::OptionBool *>(
 parser.add_init_value(std::unique_ptr<libdnf5::OptionBool>(new libdnf5::OptionBool(false))));...is that it won't fit when it's embedded on the documentation page, without forcing the reader to scroll horizontally.
Is there an override comment that can stop the formatter from re-wrapping it? I really think it reads better, for the documentation, if the line length is kept down to fit the page format.
There was a problem hiding this comment.
You can do this:
int formatted_code;
// clang-format off
void unformatted_code ;
// clang-format on
void formatted_code_again;
If the disable comment was at the very top of the page we could hide it by changing the include lines again so it doesn't complicate the template.
(I have tested it only briefly but I think if the // clang-format on is omitted it disables the formatting for the one file only.)
There was a problem hiding this comment.
@kontura Done, thanks! I think that looks much better. I also made some other changes, I'll add some review comments about those.
|
I have a feeling the formatter is still going to complain about that one line. (Edit: I was right, so I just surrendered and did what it wants. But I still think it makes the documentation harder to read.) |
The formatter wants to unwrap some lines of code to make them longer than will fit the width of the documentation when embedded.
| @@ -16,37 +27,42 @@ void TemplateCommand::set_argument_parser() { | |||
| auto & ctx = get_context(); | |||
| auto & parser = ctx.get_argument_parser(); | |||
|
|
|||
| auto & cmd = *get_argument_parser_command(); | |||
| auto & this_cmd = *get_argument_parser_command(); | |||
There was a problem hiding this comment.
I decided to rename this to match the variable name in the set_parent_command() method, to more clearly show that they represent the same object.
| // Create an option by giving it a name. It will be shown in the help message. | ||
| // Set long name, description and constant value. | ||
| // Link the option to the TemplateCommand's class member. | ||
| auto foo = parser.add_new_named_arg("foo"); | ||
| // Set the long name for the option. | ||
| foo->set_long_name("foo"); | ||
| foo->set_short_description("print foo"); | ||
| // Set the option's description (for the help message). | ||
| foo->set_description("print foo"); | ||
| // Set the constant value. This is the value assigned when an option | ||
| // which takes no value arguments appears on the command line. | ||
| foo->set_const_value("true"); | ||
| // Link the option to the TemplateCommand's class member. | ||
| foo->link_value(foo_option); |
There was a problem hiding this comment.
And, I fleshed out these comments after realizing, as I was reading the code, that I actually had no idea what the "const_value" was — and had to go digging through include/libdnf5-cli/argument_parser.hpp to find out.
|
The RPM failures are nothing to do with me, they're happening because SWIG is generating Edit: The weird thing is, the Ruby include file in question contains: #elif defined(__cplusplus)
# /* bool is a keyword in C++. */
# if defined(HAVE_STDBOOL_H) && (__cplusplus >= 201103L)
# include <cstdbool>
# endifSo it only even tries to Edit2: That |
b0f1caf
Recently on Fedora Discussions, it was brought up / discovered that the template source code in the DNF5 documentation had fallen a bit out of date, to the point where it wasn't even compilable because the internal APIs have changed so much in two years.
Since it actually says, right at the top of that page:
...It seemed clear that it was no longer remotely achieving that goal.
So, I went through and updated all of the included source code based on the current
dnf5/commands/source anddnf5/main.cpp, built and tested the template source integrated into DNF5 (as a newdnf5/commands/template/directory, just like the note says), and also updated the sample output at the end to reflect reality.I hope to do the same for the other two template documents, as well, but we'll see what happens. I wanted to at least submit this one for now, and I'll take the rest one step at a time.